do i understand it correctly, that each z param has a named counterpart, and it is mostly a shortcut + a way to see surprise yourself? I generally like the idea, but I wonder how this should be documented best, especially if some sounds have it and some don't

also, i think we need to be careful that the range doesn't differ much between z controls, too prevent something like

1. you start with sound A and z1(400)
2. you switch to sound B, your ears will fall off because z1 400 for that sound is massively out of the pleasant range

not sure how to do this, maybe let 0-1 be the safe range? would that mean we have to rescale z params to their named counterpart? just some thought

also, i think we need to be careful that the range doesn't differ much between z controls, too prevent something like

1. you start with sound A and z1(400)

2. you switch to sound B, your ears will fall off because z1 400 for that sound is massively out of the pleasant range

not sure how to do this, maybe let 0-1 be the safe range? would that mean we have to rescale z params to their named counterpart? just some thought

I think normalizing the z parameters between 0 and 1 is a great idea. I updated the pr. Also, I think sometimes they will refer to existing params where it makes sense (like with supersaw). However, there might be times when having a specific control for an oscillator might not make sense in which case you would only use z to control it.

you switch to sound B, your ears will fall off because z1 400 for that sound is massively out of the pleasant range

The beauty of Elektron boxes or Mutable is that this never happens. Whatever mode you switch into, the same set of parameters will still produce something that you can work with, albeit different. Of course, the difference can be drastic if you jump from a tonal VS atonal sound source, but given that you are using an envelope and filter, it will still be usable.

I wonder how this should be documented best

Some of the models used in macro-oscillators are kind of "self-documented". You can imagine having a model called "3osc" whose macros will help you jump between different frequency tunings around a central frequency (z1), handle the oscillator detune (z2), interpolate between waveforms (z3) and whatever (z4). It will still be 3-oscillator voice nonetheless.

The downside of this approach is that you need a lot of carefully written and optimized DSP to generate a pleasant collection. In this regard, the Mutable code itself could help.